💻 Workflow…

Gosha Syunyaev

October 25, 2024

Plan for today

What you will learn

How to set up VS Code (and why?)
How to use basic Git-Github combo
How to use Quarto (in VS Code or RStudio)

What you will not learn

What is the absolute best setup
How to deal with the fact that co-authors use MS Word, Overleaf, etc.
What is the meaning of life

github.com/gerasy1987/workflow_workshop contains materials we will go over today
github.com/gerasy1987/dotfiles contains useful links and configuration files

VS Code

VS Code?

No, if

You only work in R
You do not want to pay entry costs
You get overwhelmed by the need for customization

Yes, if

You often have to jump between applications, e.g. RStudio or LaTeX editor
You find yourself using mouse too often
You often struggle to find the right command or option

VS Code!

One of the most used IDEs in the world (~14.24%) \(\Rightarrow\) Many extensions
Has extremely customizable interface
Has outstanding keyboard shortcuts customization
Works with anything (even has packages for Overleaf and Mathematica)
Has an (overwhelming) number of packages working with LLMs

Let’s go get it

Install VS Code at code.visualstudio.com/download
Install languageserver in R
Install the R extension for Visual Studio Code
- Code completion (IntelliSense) works out of the box!
To enhance the experience of using R in VS Code, the following packages are recommended:
- radian: A modern R console that corrects many limitations of the official R terminal and supports many features such as syntax highlighting and auto-completion
- httpgd: An R package to provide a graphics device that asynchronously serves SVG graphics via HTTP and WebSockets. This package is required by the interactive plot viewer of the R extension for VS Code

Git/GitHub

What is Git?

Git + GitHub

Version Control: Provides a robust system that tracks changes and manages project history.
Branching and Merging: Supports branching and merging, enabling isolated development of features or fixes.
History and Reversion: Maintains a detailed history of changes, allowing easy reversion to previous states.
Offline Work: Allows for offline work with local repositories.

Dropbox/Overleaf/Google Docs

Real-time Collaboration: More suited for simpler, real-time collaboration.
Limited Branching: Does not inherently support branching and merging.
Basic Versioning: Focuses on file versioning without detailed change tracking.
Online Requirement: Requires internet access for syncing and collaboration.

Git?

No, if

Project is primarily individual and does not involve extensive collaboration.
Not comfortable with command-line tools or prefer simpler file management systems.

Yes, if

Multiple co-authors and need to track changes in documents AND data
Need to maintain a clear history of your project’s development and revisions.
You require a reliable backup system for your research files.

Different projects

No, if

%%{init: {
  'theme': 'base',
  'gitGraph': {'showCommitLabel': false, 'parallelCommits': true}
  } }%%
gitGraph
   commit id: "Initial commit" tag: "Initial"
   commit
   commit tag: "Pretty figures"
   commit
   commit tag: "Journal submission"

Yes, if

%%{init: {
  'theme': 'base',
  'gitGraph': {'showCommitLabel': false, 'parallelCommits': true}
  } }%%
gitGraph
   commit id: "Initial commit" tag: "Initial"
   commit
   branch Jimbo
   checkout Jimbo
   commit tag: "Nice figures"
   checkout main
   branch Gosha
   checkout Gosha
   commit
   checkout main
   merge Jimbo
   commit
   checkout Gosha
   merge main
   commit tag: "Code speedup"
   checkout Jimbo
   commit
   checkout main
   merge Gosha
   merge Jimbo
   commit tag: "Journal submission"

But how does Jimbo get access?

via a remote Hub, like GitHub:

Create a GitHub repo (if does not exist already)

git init

(under the hood)

Create a local copy of the repo

git clone <repository-url>

Do some work

Git won’t help

Stage and Commit your work
- (optionally) selectively save files to commit to logically categorize work

git add <file-name> # or . to add everything
git commit -m "Your commit message"

Push your work back

git push

We can interact with git directly via command line (terminal), or IDE like RStudio or VS Code

It all starts when we create an instance of git and we tell it to track certain files in a folder.

When the files are modified, Git knows the current state is different from the one it saved on the previous knot on the timeline.
Once we modified something and we want to save our progress, we stage the file. We tell git we’re prepared to save a given file in it’s current state for the next knot we create.

We can choose which files we want to stage. For instance, you can make two commits to separate work you did on the LaTeX paper and on the code so it’s easier to review in the future.

When we want to save the state of the project as a whole we create a new knot on the timeline by telling git to commit. Git will save state of all of the staged files we said we wanted to commit, and creates a tamper-proof point on the timeline we can come back to later. Each (commit/knot) has a unique name generated from the state of the project.

Each commit has a small comment so you can review changes in the future.
Theres’s and extra state: Ignored. We can tell git to not record chanegs on things we either don’t want to share with the internet, things that don’t change, or very big things like simulation data.

Git branching

Creating and Switching Branches

Create a new branch:
```
git branch <branch-name>
```
Switch to a branch:
```
git checkout <branch-name>
```
Create and switch to a new branch:
```
git checkout -b <branch-name>
```

Merging Branches

Merge a branch into the current branch:
```
git merge <branch-name>
```
Delete a branch after merging:
```
git branch -d <branch-name>
```
Force delete a branch:
```
git branch -D <branch-name>
```

One does not simply…

You Don’t Need to Remember All Git Commands

It’s impossible to remember every single Git command
Focus on mastering a few essential commands
Use git help or online resources for the rest
Embrace the power of AI and auto-complete from history

Let’s go get it

Installation instructions at git-scm.com/book/en/v2/Getting-Started-Installing-Git (or just Google)
clone two repositories:
- https://github.com/gerasy1987/workflow_workshop.git
- https://github.com/gerasy1987/dotfiles

Quarto

Quarto?

An open-source scientific and technical publishing system
Allows you to bring together everything:
- LaTeX + Markdown + HTML for text editing
- R/Python/Julia for statistics
- Produce manuscripts, presentations, dashboards, websites…
- Produce output in PDF, HTML or Word format

There is no reason not to switch beyond entry costs!

Quarto!

It is fairly easy to start the switch
- If you used R Markdown before, then it is backward compatible
- If you used raw LaTeX the only new thing to learn how to switch is YAML preamble

It is better than alternative in any respect
- It is more versatile
- Easier to read
- Has Visual editor (for those who remember LyX)
- Allow to do many things (papers, presentation, code, webpages)
- Forces you to learn new useful things (e.g. YAML and HTML)

Papers

Write papers as normal
Use executable chunks with code ```
Use Markdown natively, e.g.
- * around word will make it italic and ** will make it bold
- # for section, ## for subsection, etc.
- []() for links and ![]() for images

Presentations

beamer for LaTeX slides
Powerpoint for when you have to collaborate via Office
Revealjs – essentially the replacement for xaringan, but with Pandoc-native syntax

Revealjs

revealjs is an open source HTML presentation framework
Enables anyone with a web browser to create fully-featured and beautiful presentations for free.
revealjs for Quarto is a framework for turning Pandoc-friendly markdown + code into beautiful slides
Shines when used for interactive slides, data results and math

Executable code

library(ggplot2)
ggplot(mtcars, aes(hp, mpg, color = am)) +
  geom_point() +
  geom_smooth(formula = y ~ x, method = "loess")

Pretty code

Over 20 syntax highlighting themes available
Default theme optimized for accessibility

# Define a server for the Shiny app
function(input, output) {
  
  # Fill in the spot we created for a plot
  output$phonePlot <- renderPlot({
    # Render a barplot
  })
}

Code animations

Over 20 syntax highlighting themes available
Default theme optimized for accessibility

# Define a server for the Shiny app
function(input, output) {
  
  # Fill in the spot we created for a plot
  output$phonePlot <- renderPlot({
    # Render a barplot
    barplot(WorldPhones[,input$region]*1000, 
            main=input$region,
            ylab="Number of Telephones",
            xlab="Year")
  })
}

LaTeX equations

MathJax rendering of equations to HTML

\begin{gather*}
a_1=b_1+c_1\\
a_2=b_2+c_2-d_2+e_2
\end{gather*}

\begin{align}
a_{11}& =b_{11}&
  a_{12}& =b_{12}\\
a_{21}& =b_{21}&
  a_{22}& =b_{22}+c_{22}
\end{align}

\[\begin{gather*} a_1=b_1+c_1\\ a_2=b_2+c_2-d_2+e_2 \end{gather*}\] \[\begin{align} a_{11}& =b_{11}& a_{12}& =b_{12}\\ a_{21}& =b_{21}& a_{22}& =b_{22}+c_{22} \end{align}\]

Markdown tables

| Default | Left | Right | Center |
|---------|:-----|------:|:------:|
| 12      | 12   |    12 |   12   |
| 123     | 123  |   123 |  123   |
| 1       | 1    |     1 |   1    |

: Demonstration of pipe table syntax

Demonstration of pipe table syntax
Default	Left	Right	Center
12	12	12	12
123	123	123	123
1	1	1	1

	mpg	cyl	disp	hp	drat	wt	qsec	vs	am	gear	carb
Mazda RX4	21.0	6	160.0	110	3.90	2.620	16.46	0	1	4	4
Mazda RX4 Wag	21.0	6	160.0	110	3.90	2.875	17.02	0	1	4	4
Datsun 710	22.8	4	108.0	93	3.85	2.320	18.61	1	1	4	1
Hornet 4 Drive	21.4	6	258.0	110	3.08	3.215	19.44	1	0	3	1
Hornet Sportabout	18.7	8	360.0	175	3.15	3.440	17.02	0	0	3	2
Valiant	18.1	6	225.0	105	2.76	3.460	20.22	1	0	3	1
Duster 360	14.3	8	360.0	245	3.21	3.570	15.84	0	0	3	4
Merc 240D	24.4	4	146.7	62	3.69	3.190	20.00	1	0	4	2
Merc 230	22.8	4	140.8	95	3.92	3.150	22.90	1	0	4	2
Merc 280	19.2	6	167.6	123	3.92	3.440	18.30	1	0	4	4
Merc 280C	17.8	6	167.6	123	3.92	3.440	18.90	1	0	4	4
Merc 450SE	16.4	8	275.8	180	3.07	4.070	17.40	0	0	3	3
Merc 450SL	17.3	8	275.8	180	3.07	3.730	17.60	0	0	3	3
Merc 450SLC	15.2	8	275.8	180	3.07	3.780	18.00	0	0	3	3
Cadillac Fleetwood	10.4	8	472.0	205	2.93	5.250	17.98	0	0	3	4
Lincoln Continental	10.4	8	460.0	215	3.00	5.424	17.82	0	0	3	4
Chrysler Imperial	14.7	8	440.0	230	3.23	5.345	17.42	0	0	3	4
Fiat 128	32.4	4	78.7	66	4.08	2.200	19.47	1	1	4	1
Honda Civic	30.4	4	75.7	52	4.93	1.615	18.52	1	1	4	2
Toyota Corolla	33.9	4	71.1	65	4.22	1.835	19.90	1	1	4	1
Toyota Corona	21.5	4	120.1	97	3.70	2.465	20.01	1	0	3	1
Dodge Challenger	15.5	8	318.0	150	2.76	3.520	16.87	0	0	3	2
AMC Javelin	15.2	8	304.0	150	3.15	3.435	17.30	0	0	3	2
Camaro Z28	13.3	8	350.0	245	3.73	3.840	15.41	0	0	3	4
Pontiac Firebird	19.2	8	400.0	175	3.08	3.845	17.05	0	0	3	2
Fiat X1-9	27.3	4	79.0	66	4.08	1.935	18.90	1	1	4	1
Porsche 914-2	26.0	4	120.3	91	4.43	2.140	16.70	0	1	5	2
Lotus Europa	30.4	4	95.1	113	3.77	1.513	16.90	1	1	5	2
Ford Pantera L	15.8	8	351.0	264	4.22	3.170	14.50	0	1	5	4
Ferrari Dino	19.7	6	145.0	175	3.62	2.770	15.50	0	1	5	6
Maserati Bora	15.0	8	301.0	335	3.54	3.570	14.60	0	1	5	8
Volvo 142E	21.4	4	121.0	109	4.11	2.780	18.60	1	1	4	2

Interactive slides

Include Jupyter widgets and htmlwidgets in your presentations

Let’s go get it

https://quarto.org/

Additionally, you can download and install Quarto using:

Homebrew (macOS/linux)

Bash

brew install quarto

Chocolatey (Windows)

PowerShell

choco install quarto